/*
Copyright (c) 2008,2009, David Beck

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/

/**
   @file rx.hh
   @brief RxRPC security model introduction

   @page rx Introduction of RxRPC security model

   @section rxmain New RxRPC security model

   @subsection rxintro The new rt0d4/Rx security model

   RxRPC is part of AFS, OpenAFS, Arla and linux kernel. It was developed for
   AFS but designed to be useful for standalone applications as well. RxRPC
   provides RPC services just like Sun RPC, on which RxRPC (or Rx) was based on.

   Rx has a pluggable security model that is based on customizable callbacks.
   Rx has two security models built in: the @em null model and the @em kerberos
   based rxkad model. The new rt0d4::rx model provides the neccessary functions
   and callbacks to be integrated into Rx. (rt0d4_rx.h)

   The rt0d4::rx model is based on OpenSSL. It first exchanges asymetric keys
   based on elliptic curve cryptography. This allows to calculate a session
   key. The session key is then used with blowfish encryption to encrypt the
   traffic. The model allows to pass server and client certificates. This
   may be used to check the client and server identity. To facilitate that,
   callback functions may be specified. The client can also send login and
   password that can be checked on the server side by a user supplied callback.
   The login and the password strings are transfered in an encrypted form.

   The only incompatibility betweed Rx and the new security model comes from
   the fact that the challenge response authentication is only started after
   the first call was made on the client side. That has the consequence that
   the first packet would be transmitted before the session key is available.
   To prevent the transmission of possible sensible data unencrypted this
   first packet will be garbled (filled with garbage data). This in turn
   results an error code for the first call (-455 = RXGEN_OPCODE). This is a
   @em transient error so if that happens, then the call should be retried once.

   @subsection tipuse Simple usage scenario of Rx with null authentication

   @subsubsection clicodenull Client code:

     @li rxnull_NewClientSecurityObject( );
     @li rx_NewConnection(...);
     @li rx_Finalize();

   @subsubsection sercodenull Server code:

     @li rx_Init(...);
     @li rxnull_NewServerSecurityObject( );
     @li rx_NewService(...);
     @li rx_StartServer(...);
     @li rx_Finalize();

   @subsection tipuse2 Simple usage scenario of RT0D4

   @subsubsection clicodert0d4 Client code:

     @li rt0d4_rx_NewClientSecurityObject( );
     @li rx_NewConnection(...);
     @li rx_Finalize();

   @subsubsection sercodert0d4 Server code:

     @li rx_Init(...);
     @li rt0d4_rx_NewServerSecurityObject( );
     @li rx_NewService(...);
     @li rx_StartServer(...);
     @li rx_Finalize();

   @subsection tipuse3 Simple usage scenario of RT0D4 with credential checks

   @subsubsection clicodert0d4b Client code:

     @li rt0d4_rx_NewClientSecurityObject( );
     @li rt0d4_rx_SetOwnCredentials(...);
     @li rx_NewConnection(...);
     @li rx_Finalize();

   @subsubsection sercodert0d4n Server code:

     @li rx_Init(...);
     @li rt0d4_rx_NewServerSecurityObject( );
     @li rt0d4_rx_SetPeerCertValidateCallBack(...);
     @li rx_NewService(...);
     @li rx_StartServer(...);
     @li rx_Finalize();

   For more usage examples please check the tests in the rt0d4/rx/test directory.
   t__demo1_client and t__demo1_server give more clue about it. Also check the documentation
   in the rt0d4_rx.h file.

   @subsection rtprop Notes on Rx+RT0D4

   This security model encrypts all communication between the peers except for
   the first handshake packages.
*/
